<!DOCTYPE html>
<html lang="en">
	<head>
		<title>Installation and Setup - Wave Framework</title>
		<meta charset="utf-8">
		<meta name="viewport" content="width=device-width"/> 
		<link type="text/css" href="../style.css" rel="stylesheet" media="all"/>
		<link rel="icon" href="../../favicon.ico" type="image/x-icon"/>
		<link rel="icon" href="../../favicon.ico" type="image/vnd.microsoft.icon"/>
	</head>
	<body>
	
		<h1>Installation and Setup</h1>
		
			<ul>
				<li><a href="#index-introduction">Introduction</a></li>
				<li><a href="#index-installing-wave-framework">Installing Wave Framework</a></li>
				<li><a href="#index-server-requirements">Server Requirements</a></li>
				<li><a href="#index-successful-output-from-compatibility-script">Successful Output from Compatibility Script</a></li>
			</ul>
			
			<h2 id="index-introduction">Introduction</h2>
			
				<p>This document gives a complete overview about the installation procedure of Wave Framework to a web server.
		
			<h2 id="index-installing-wave-framework">Installing Wave Framework</h2>

				<ul>
					<li><b>1</b> - Unpack the downloaded archive of Wave Framework or go to the repository folder if you downloaded through Git or Mercurial.</li>
					<li><b>2</b> - <a href="configuration.htm">Configuration</a> file '/config.ini' in root directory of the archive should be configured according to your needs. <a href="configuration.htm">Configuration</a> file has multiple comments about each setting, but they can be left undefined and unchanged at first, since the Framework is able to define defaults for most settings by itself.</li>
					<li><b>3</b> - Upload the entire archive to your server and make <a href="filesystem.htm">Filesystem</a> folder '/filesystem/' and all of its subfolders writable by PHP with command 'chmod 0755' or giving rights using an FTP program like FileZilla (Right click on folder -&gt; File Permissions -&gt; Numeric value -&gt; 0755). This is not required on Windows server (or Windows localhost) since Windows has folders writable by default.
						<ul>
							<li>On some servers the FTP account is configured so that 0755 will not allow PHP to actually write to these folders if you set the rights over FTP, so you should either ask the administrator to change the account permissions or set the folder permissions to 0777 and see if that works when 0755 did not (this is less secure however, so you should only do it temporarily).</li>
							<li>Some servers modify the files uploaded through FTP in some way, often breaking line breaks and thus functionality of the scripts. If you encounter problems and there is no clear error message, then make sure that the uploaded files are correctly stored on the server. Upload should work correctly if you upload files in Binary mode (In FileZilla it is 'Transfer -> Transfer Type -> Binary').</li>
						</ul>
					</li>
					<li><b>4</b> - Wave Framework requires servers ability to redirect all requests to '/index.php' file, thus Apache RewriteEngine or Nginx HttpRewriteModule has to be used. Look at points 5A or 5B, depending on your server.</li>
					<li><b>5A - Apache</b>
						<ul>
							<li>On most server setups the Apache-related settings in this list should already be enabled and everything should work, but in case you run into problems and you cannot edit Apache configuration yourself, then ask for assistance from your hosting provider.</li>
							<li>Make sure that you uploaded '/.htaccess' and '/tools/.htaccess' files to the server, as sometimes they may not be uploaded due to operating system thinking they are hidden. If possible, you should actually implement these rewrite directives from those files to your main Apache server configuration and remove the '.htaccess' files, since this can improve the performance, but if this is not possible then keeping the '.htaccess' files in your root folder is perfectly common practice.</li>
							<li>Apache also needs to support '.htaccess' directives from those files, so make sure that 'AllowOverride' setting is 'All' in Apache directory configuration. This is usually enabled by default on most servers.</li>
							<li>Since RewriteEngine is required for URL rewrites, your server needs to have the module loaded, which means that the line 'LoadModule rewrite_module modules/mod_rewrite.so' needs to be uncommented in Apache. This is usually enabled by default on most servers.</li>
							<li>On some hosting environments the line 'Options +FollowSymLinks' in '.htaccess' may throw an error, so if an error is thrown then I suggest commenting or removing that line and trying the compatibility script again.</li>
						</ul>
					</li>
					<li><b>5B - Nginx</b>
						<ul>
							<li>For rewrites to work properly you need to place the configuration settings found in '/nginx.conf' file to your Nginx server configuration. This is more complicated than setting up redirects locally on Apache servers, since a lot of Nginx servers have very different configurations and just a single configuration file (Nginx has no '.htaccess' like functionality) and you need to implement your configuration inside that main configuration. If you know a little about Nginx server configuration, then it should not be a problem.</li>
						</ul>
					</li>
					<li><b>6</b> - Test if server is set up properly by making a request to '/tools/compatibility.php' script and fix any errors that Compatibility script might throw. Warnings can be ignored, but Wave Framework works at its best if it encounters no warnings in Compatibility script, so make sure to read the messages next to warnings.</li>
					<li><b>7</b> -  Access the root file with a web browser. If 'Hello Wave' is shown together with a pretty logo, without any errors, then everything should be up and running! There is no setup script that needs to be run separately and you can start developing your application right away.
						<ul>
							<li>If the page shows an error message, then make sure that the '/filesystem/' folders are writable and that the configuration steps above have been followed.</li>
							<li>Make sure that the files were uploaded correctly and that FTP did not convert line breaks to single line in uploaded files. If it did, then fix this by uploading files in Binary mode.</li>
							<li>You can also take a look at '/tools/debugger.php' script in case you encounter errors even if Compatibility script says that everything is alright with the server. If Debugger script does not show any warnings and your page still shows errors, then the error happens in core, such as version incompatibility, file permissions and more. Double check that you have followed the previous steps.</li>
							<li>If the text is shown, but the logo picture is seems to be not found, then the problem might be that you are using a proxy that attempts to load static files by itself and the requested file '/resources/images/160x160&amp;logo.png' does not actually exist. This is because that URL includes on-demand resize parameters that can only be used when file is loaded through Wave Framework itself. You can serve static files through a proxy, but in this case you cannot use the 'dynamic loading of resources' functionality of Wave Framework.</li>
						</ul>
					<li><b>8</b> - <b>Important!</b> Make sure to change 'http-authentication-username' and 'http-authentication-password' settings in '/config.ini' file (line #36 and #37). These are used to authenticate access to developer tools in '/tools/' directory and it may pose a security risk if left unchanged as all downloaded archives have the same username and password at first.</li>
				</ul>
				
				<h3>Where to next?</h3>
				
					<p>Wave Framework has multiple tutorials you can try out in order to learn how Wave Framework can be used to build various web services and websites. Even if you have not worked with API's and MVC-specific frameworks before, getting a good grip on such a development is not very difficult with Wave. Tutorials are available in the Tutorials section <a href="../index.htm">here</a>.</p>

			<h2 id="index-server-requirements">Server Requirements</h2>

				<p>Wave Framework requires a server that allows to route all requests to <a href="gateway.htm">Index Gateway</a> file (/index.php). <a href="gateway.htm">Index Gateway</a> does not work without URL rewriting. It is possible to use Wave Framework's API without <a href="gateway.htm">Index Gateway</a>, but in this case you need to develop your own gateway that does not require such HTTP request URL rewriting.</p>

				<h3>Apache</h3>

					<p>Apache and <b>mod_rewrite</b> (RewriteEngine) is required if you intend to use <a href="gateway.htm">Index Gateway</a> for website as well as default <a href="handler_api.htm">API Handler</a>. Apache .htaccess file is included in the archive that should do everything server needs to make it work, if the mod_rewrite module is supported by Apache. Because RewriteEngine directives are loaded from local .htaccess files, then Apache also needs to support .htaccess files. If RewriteEngine has problems, then make sure that your Apache setting has 'AllowOverride' set to 'All' instead of 'None' in directory settings. RewriteEngine module is also required, so the 'LoadModule rewrite_module modules/mod_rewrite.so' line has to be included or uncommented from Apache configuration.</p>

				<h3>Nginx</h3>

					<p>Wave Framework also supports Nginx server. Nginx does not have .htaccess style local settings for web server, thus these settings have to be written in Nginx configuration itself. Recommended settings for Nginx are stored in /nginx.conf file. You have to manually place them in Nginx server configuration.</p>

				<h3>PHP</h3>

					<p>PHP version 5.3.3 or newer is required.</p>
					<p>Wave Framework also uses <b>Zlib</b> extension for compressed output, <b>PDO</b> extension for database connections, <b>GD Image Library</b> is used to dynamically resize images, <b>Mcrypt</b> is used for crypted input and output, <b>Fileinfo</b> extension for <a href="handler_file.htm">File Handler</a> and <b>Zip</b> extension for automatic update scripts together with <b>FTP</b>, <b>APC</b> is used to improve the performance of PHP and caching, <b>SimpleXML</b> is used to support XML stream as API input, <b>cURL</b> is used for external requests, . These extensions come with PHP and should be enabled by default, but if they are not enabled then compatibility script will warn you about it and recommend what you should do.</p>

				<h3>Filesystem</h3>

					<p>It is also required that <b>/filesystem/</b> folder and all of its subfolders are writable by PHP. This is not required on Windows server, since folders are already writable.</p>

				<h2 id="index-successful-output-from-compatibility-script">Successful output from Compatibility Script</h2>

					<p>
					SUCCESS: PHP is version 5.3.0 or above<br/>
					SUCCESS: PHP setting short_open_tag is enabled<br/>
					SUCCESS: PDO is supported<br/>
					SUCCESS: PDO MySQL is supported<br/>
					SUCCESS: PDO SQLite is supported<br/>
					SUCCESS: PDO PostgreSQL is supported<br/>
					SUCCESS: PDO Oracle is supported<br/>
					SUCCESS: PDO MSSQL is supported<br/>
					SUCCESS: Zlib is supported<br/>
					SUCCESS: APC PHP is supported<br/>
					SUCCESS: SimpleXML is supported<br/>
					SUCCESS: cURL is supported<br/>
					SUCCESS: Fileinfo is supported<br/>
					SUCCESS: Mcrypt is supported<br/>
					SUCCESS: Zip is supported<br/>
					SUCCESS: FTP is supported<br/>
					SUCCESS: Memcache is supported<br/>
					SUCCESS: GD Graphics Library is supported<br/>
					SUCCESS: Apache server is used<br/>
					SUCCESS: Apache mod_rewrite extension is supported<br/>
					SUCCESS: .htaccess file is present<br/>
					SUCCESS: /filesystem/ is writable</br>
					SUCCESS: /filesystem/cache/ is writable</br>
					SUCCESS: /filesystem/cache/images/ is writable</br>
					SUCCESS: /filesystem/cache/output/ is writable</br>
					SUCCESS: /filesystem/cache/resources/ is writable</br>
					SUCCESS: /filesystem/cache/custom/ is writable</br>
					SUCCESS: /filesystem/cache/tags/ is writable</br>
					SUCCESS: /filesystem/messenger/ is writable</br>
					SUCCESS: /filesystem/keys/ is writable</br>
					SUCCESS: /filesystem/limiter/ is writable</br>
					SUCCESS: /filesystem/sessions/ is writable</br>
					SUCCESS: /filesystem/logs/ is writable</br>
					SUCCESS: /filesystem/errors/ is writable</br>
					SUCCESS: /filesystem/tokens/ is writable</br>
					SUCCESS: /filesystem/tmp/ is writable</br>
					SUCCESS: /filesystem/userdata/ is writable</br>
					SUCCESS: /filesystem/backups/ is writable</br>
					SUCCESS: /filesystem/static/ is writable</br>
					SUCCESS: /filesystem/updates/ is writable</br>
					SUCCESS: /filesystem/data/ is writable
					</p>
			
	</body>
</html>